BPTRAP 1.0
==========

Copyright (C) 1996 Frank Heckenbach

DESCRIPTION:
------------
The Unit BPTrap allows you to trap runtime errors in a Borland Pascal
program. That means, a runtime error will not abort the program but pass
the control back to a point within the program.

It should run with Borland Pascal 7.0 on all three platforms (Real mode,
Protected mode and Windoze).

The Usage is simple. See the TrapDemo program:

Calling the Trap procedure will install Trap and return the value False.

Whenever a runtime error occurs after installing Trap, the program will be
continued at the point from which Trap was installed! This means, the program
will JUMP BACK (and thereby cause a loop - without a For, While or Repeat
statement in your program)! To differentiate this from the installation call,
now the value True is "returned". By testing the return value, a loop can be
avoided (see the TrapDemo program), but sometimes the loop is what is wanted.

You can uninstall Trap by calling UnTrap. This function will return True
iff it could uninstall Trap. If it could not, reasons may be that Trap was
not installed or that other Exitprocs were installed after Trap.

When the program terminates (by reaching the end or by a Halt or Keep
statement) and a runtime error was trapped during the run, Trap will set the
Exitcode and Erroraddr variables to indicate the trapped error. So the
program will display a "correct" runtime error message (even if it has kept
running for a while after the trapped error!). One advantage of this is that
if you are using the integrated debugger (real mode), it will show you the
error position in your source code as usual.

If you have any hints, suggestions or error reports (apart from runtime
errors trapped by my unit ;-), I will be interested to hear from you.

CAUTIONS:
---------
* The procedure that calls Trap must NOT return as long as Trap is installed
  (so it is safest to call Trap from the main program, if possible)!

* You must call the function Trap AFTER installing all other Exitprocs
  (if any).

* In Real mode: You must NOT call it from an overlayed unit.

* In Protected mode and Windoze: You must call it from a code segment with
  the following attributes: FIXED PRELOAD PERMANENT. (I am not sure if this
  is really necessary...).

* After trapping a runtime error, your program might not be is a stable state.
  If the runtime error was a "minor" one (such as a range checking or
  arithmetic error) and if the other cautions have been respected, it should
  not be a problem. But if you e.g. write a larger application and use trap
  to prevent a sudden abort, you should make the program terminate regularly
  as soon as possible after a trapped error (maybe telling the user to
  terminate the program and report the error to you).

* Since the exit proc JUMPS back, it has all the negative effects that a GOTO
  would have! (And even a global GOTO!) You should be aware of the
  consequences of all active procedures being terminated at some point!

* The program has been tested with BP version 7.0 only. It may well work with
  other BP versions, but you will have to try that on your own risk.
  As a safety measure, I inserted two lines that will prevent the unit from
  compiling with any BP version different from 7.0. To still do that, you
  have to delete or comment these two lines.

* The program has been tested mainly in real mode, so if you want to use it
  seriously on another platform (Protected mode or Windoze), you should test
  it more thoroughly.

FILES:
------
The package consists of the following files:

README.TXT     This file
COPYING        The Gnu General Public License
BPTRAP.PAS     The Trap unit
TRAPDEMO.PAS   A simple demo program using the Trap unit, working on all
               three platforms

LEGAL STUFF:
------------
The Trap unit and the Trap demo program (both below referred to as
"the program") are Copyright (C) 1996 Frank Heckenbach.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, version 1, for NON-COMMERCIAL use.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

For using this program commercially in any way, the GNU General
Public License is NOT applicable. Any commercial use of the program
must be explicitly allowed by the author and will usually require
payment of a royalty.

Borland Pascal is a registered trademark of Borland International, Inc.

Windoze is not a trademark ;-)

Frank Heckenbach
Email: heckenb@mi.uni-erlangen.de
       alternatively: fn106@fim.uni-erlangen.de